Jump to Table of Contents Collapse Sidebar

did:web Method Specification

did:web Method Specification

Unofficial Draft

More details about this document
Latest published version:
none
Latest editor's draft:
https://w3c-ccg.github.io/did-method-web/
History:
Commit history
Editors:
Michael Prorock (mesur.io)
Oliver Terbu (Consensys)
Authors:
Christian Gribneau (Ology Newswire, Inc.)
Michael Prorock (mesur.io)
Orie Steele (Transmute)
Oliver Terbu (Consensys)
Mike Xu (Consensys)
Dmitri Zagidulin (Digital Bazaar)
Feedback:
GitHub w3c-ccg/did-method-web (pull requests, new issue, open issues)

Copyright © 2024 the document editors/authors. Text is available under the Creative Commons Attribution 4.0 International Public License; additional terms may apply.

Abstract

DIDs that target a distributed ledger face significant practical challenges in bootstrapping enough meaningful trusted data around identities to incentivize mass adoption. We propose a new DID method using a web domain's existing reputation.

Status of This Document

This document is a draft of a potential specification. It has no official standing of any kind and does not represent the support or consensus of any standards organization.

1. Introduction

1.1 Preface

The Web DID method specification conforms to the requirements specified in the Decentralized Identifiers v1.0 Specification [DID-CORE]. For more information about DIDs and DID method specifications, please also see the [DID-PRIMER]

1.2 Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

1.3 Examples

Example 1: Example did:web DID document using JSON Web Keys 
{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:web:example.com",
  "verificationMethod": [
    {
      "id": "did:web:example.com#key-0",
      "type": "JsonWebKey2020",
      "controller": "did:web:example.com",
      "publicKeyJwk": {
        "kty": "OKP",
        "crv": "Ed25519",
        "x": "0-e2i2_Ua1S5HbTYnVB0lj2Z2ytXu2-tYmDFf8f5NjU"
      }
    },
    {
      "id": "did:web:example.com#key-1",
      "type": "JsonWebKey2020",
      "controller": "did:web:example.com",
      "publicKeyJwk": {
        "kty": "OKP",
        "crv": "X25519",
        "x": "9GXjPGGvmRq9F6Ng5dQQ_s31mfhxrcNZxRGONrmH30k"
      }
    },
    {
      "id": "did:web:example.com#key-2",
      "type": "JsonWebKey2020",
      "controller": "did:web:example.com",
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "P-256",
        "x": "38M1FDts7Oea7urmseiugGW7tWc3mLpJh6rKe7xINZ8",
        "y": "nDQW6XZ7b_u2Sy9slofYLlG03sOEoug3I0aAPQ0exs4"
      }
    },
  ],
  "authentication": [
    "did:web:example.com#key-0",
    "did:web:example.com#key-2"
  ],
  "assertionMethod": [
    "did:web:example.com#key-0",
    "did:web:example.com#key-2"
  ],
  "keyAgreement": [
    "did:web:example.com#key-1", 
    "did:web:example.com#key-2"
  ]
}
Example 2: Example did:web DID document using an ethereum address 
{
  "@context": ["https://www.w3.org/ns/did/v1", "https://w3id.org/security/suites/secp256k1recovery-2020/v2"],
  "id": "did:web:example.com",
  "verificationMethod": [{
      "id": "did:web:example.com#address-0",
      "type": "EcdsaSecp256k1RecoveryMethod2020",
      "controller": "did:web:example.com",
      "blockchainAccountId": "eip155:1:0x89a932207c485f85226d86f7cd486a89a24fcc12"
  }],
  "authentication": [
      "did:web:example.com#address-0"
  ]
}

2. Web DID Method Specification

2.1 Target system

The target system of the Web DID method is the host (or domain if the host is not specified) name when the domain specified by the DID is resolved through the Domain Name System (DNS).

2.2 Method name

The namestring that shall identify this DID method is: web. A DID that uses this method MUST begin with the following prefix: did:web. Per the DID specification, this string MUST be in lowercase. The remainder of the DID, after the prefix, is specified below.

2.3 Method-specific identifier

The method specific identifier is a fully qualified domain name that is secured by a TLS/SSL certificate with an optional path to the DID document. The formal rules describing valid domain name syntax are described in [RFC1035], [RFC1123], and [RFC2181].

The method specific identifier MUST match the common name used in the SSL/TLS certificate, and it MUST NOT include IP addresses. A port MAY be included and the colon MUST be percent encoded to prevent a conflict with paths. Directories and subdirectories MAY optionally be included, delimited by colons rather than slashes. 

web-did = "did:web:" domain-name
web-did = "did:web:" domain-name * (":" path)
Example 3: Example Web Method DIDs 
did:web:w3c-ccg.github.io

did:web:w3c-ccg.github.io:user:alice

did:web:example.com%3A3000

2.4 Key Material and Document Handling

Due to the way most web servers present content, it is likely that a particular did:web document will be served with a media type of application/json. If a document is retrieved and it is named did.json, a few processing rules should apply:

Whenever a DID URL is present within a did:web document, it must be an absolute URL.

Note

This includes URLs inside of embedded key material and other metadata, and prevents key confusion attacks.

2.5 DID method operations

2.5.1 Create (Register)

There is intentionally no HTTP API specified for did:web method operations leaving programmatic registrations and management to be defined by each implementation, or based on their own requirements in their web environment.

Creating a DID is done by:

  1. applying at a domain name registrar for use of a domain name and
  2. storing the location of a hosting service, the IP address at a DNS lookup service
  3. creating the DID document JSON-LD file including a suitable keypair, e.g. using the Koblitz Curve, and storing the did.json file under the well-known URL to represent the entire domain, or under the specified path if many DIDs will be resolved in this domain.

For example, for the domain name w3c-ccg.github.io, the did.json will be available under the following URL:

Example 4: Creating the DID 
did:web:w3c-ccg.github.io
 -> https://w3c-ccg.github.io/.well-known/did.json

If an optional path is specified rather the bare domain, the did.json will be available under the specified path:

Example 5: Creating the DID with optional path 
did:web:w3c-ccg.github.io:user:alice
 -> https://w3c-ccg.github.io/user/alice/did.json

If an optional port is specified on the domain, the port colon splitting the host and the port MUST be percent encoded to prevent collision with the path.

Example 6: Creating the DID with optional path and port 
did:web:example.com%3A3000:user:alice
 -> https://example.com:3000/user/alice/did.json

2.5.2 Read (Resolve)

The following steps MUST be executed to resolve the DID document from a Web DID:

  1. Replace ":" with "/" in the method specific identifier to obtain the fully qualified domain name and optional path.
  2. If the domain contains a port percent decode the colon.
  3. Generate an HTTPS URL to the expected location of the DID document by prepending https://.
  4. If no path has been specified in the URL, append /.well-known.
  5. Append /did.json to complete the URL.
  6. Perform an HTTP GET request to the URL using an agent that can successfully negotiate a secure HTTPS connection, which enforces the security requirements as described in 2.6 Security and privacy considerations.
  7. Verify that the ID of the resolved DID document matches the Web DID being resolved.
  8. When performing the DNS resolution during the HTTP GET request, the client SHOULD utilize [RFC8484] in order to prevent tracking of the identity being resolved.

2.5.3 Update

To update the DID document, the did.json has to be updated. Please note that the DID will remain the same, but the contents of the DID document could change, e.g., by including a new verification key or adding service endpoints.

Note

Managing updates to the DID Document using a version control system such as git and continious integration system such as GitHub Actions can provide support for authentication and audit history.

Note: HTTP API

There is no HTTP API specified for the update process leaving programmatic registrations and management to be defined by each implementation.

2.5.4 Deactivate (Revoke)

To delete the DID document, the did.json has to be removed or has to be no longer publicly available due to any other means.

2.6 Security and privacy considerations

This section is non-normative.

2.6.1 Authentication and Authorization

This DID method does not specify any authentication or authorization mechanism for writing to, removing or creating the DID Document, leaving it up to implementations to protect did:web documents as with any other web resource.

It is up to implementer to secure their web environments according to industry best practices for updating or otherwise managing web content based on the specific needs of their threat environment.

2.6.2 DNS Considerations

2.6.2.1 DNS Security Considerations

DNS presents many of the attack vectors that enable active security and privacy attacks on the did:web method and it's important that implementors address these concerns via proper configuration of DNS. For example, without proper security of the DNS resolution via DNS over HTTPS it's possible for active attackers to intercept the result of the DNS resolution via a Man in the Middle attack which would point at a malicious server with the incorrect DID Document.

Additionally, implementors should be aware of issues presented by a Spoofed DNS records where the record returned by a malicious DNS Server is inauthentic and allows the record to be pointed at a malicious server which contains a different DID Document. To prevent this type of issue, usage of DNSSEC which is RFC4033, RFC4034, and RFC4035.

2.6.2.2 DNS Privacy Considerations

Due to the nature of the did:web method relying upon a DNS in order to resolve the web server, all resolutions of a did:web identifier have the potential to be tracked by a DNS provider. Additionally, due to the DID Document being stored on a web server, each time the DID Document resource is retrieved, the web server has the ability to track the resolution of the DID Document. To mitigate the issue of the relying party being tracked when resolving the DID Document the relying party should look to either use a trusted universal resolver service to gain herd privacy, utilize a VPN service or perform a resolution over the TOR network. Another emerging solution that will be useful to address this is draft-pauly-dprive-oblivious-doh-03

2.6.3 DID Document Integrity Verification

Additional mechanisms such as Hashlinks MAY be utilized to aid in integrity protection and verification of the DID document.
Under such a scenario the hash of the DID document could be recorded to a trusted or distributed store and the retriever of the DID document would generate a hash of the DID document in their posession with the hash retrieved to ensure that no tampering with the DID document had occurred.

2.6.4 In-transit Security

Guidance from NIST SP 800-52 Rev. 2 or superceding, MUST be followed for delivery of a did:web document.

It is additionally recommended to adhere to the latest recommendations from OWASP's Transport Layer Protection Cheat Sheet [OWASP-TRANSPORT] for hardening TLS configurations.

Consult NIST SP 800-57 for guidance on cryptoperiod, which is the time span during which a specific key is authorized for use or in which the keys for a given system or application may remain in effect.

TLS configuration MUST use at least SHA256, and SHOULD use SHA384, POLY1305, or stronger, depending on the needs of your operating environment.

Delete action MAY be performed by domain name registrars or DNS lookup services.

As of this writing, TLS 1.2 or higher SHOULD be configured to use only strong ciphers suites and to use sufficiently large key sizes. As recommendations may be volatile these days, only the very latest recommendations should be used. However, as a rule of thumb, the following set of suites is a reasonable starting point:

  • ECDHE with one of the strong curves {X25519, brainpoolP384r1, NIST P-384, brainpoolP256r1, NIST P-256} shall be used as key exchange.
  • AESGCM or ChaCha20 with 256 bit large keys shall be used for bulk encryption
  • ECDSA with one of the strong curves {brainpoolP384r1, NIST P-384, brainpoolP256r1, NIST P-256} or RSA (at least 3072) shall be used.
  • Authenticated Encryption with Associated Data (AEAD) shall be used as Mac.

Examples of strong SSL/TLS configurations for now are:

  • ECDHE-ECDSA-AES256-GCM-SHA384, TLSv1.2, Kx=ECDH, Au=ECDSA, Enc=AESGCM(256), Mac=AEAD
  • ECDHE-RSA-AES256-GCM-SHA384, TLSv1.2, Kx=ECDH, Au=RSA Enc=AESGCM(256), Mac=AEAD
  • ECDHE-ECDSA-CHACHA20-POLY1305, TLSv1.2, Kx=ECDH, Au=ECDSA, Enc=ChaCha20-Poly1305, Mac=AEAD
  • ECDHE-RSA-CHACHA20-POLY1305, TLSv1.2, Kx=ECDH, Au=RSA, Enc=ChaCha20-Poly1305, Mac=AEAD
  • ECDHE-RSA-AES256-GCM-SHA384, TLSv1.2, Kx=ECDH, Au=RSA, Enc=AESGCM(256), Mac=AEAD
  • ECDHE-ECDSA-AES256-GCM-SHA384, TLSv1.2, Kx=ECDH, Au=ECDSA, Enc=AESGCM(256), Mac=AEAD

2.6.5 International Domain Names

[DID-CORE] identifier syntax does not allow Unicode in method name nor method specific identifiers.

Implementers should be cautious when implementing support for DID URLs that rely on domain names or path components that contain Unicode characters.

See also:

2.6.6 Optional Path Considerations

When optional paths to DID documents are used to resolve documents rather than bare domains, verification with signed data proves that the entity in control of the file indicated in the path has the private keys. It does not prove that the domain operator has the private keys.

This example: 

did:web:example.com:u:bob

resolves to the DID document at: 

https://example.com/u/bob/did.json

In this scenario, it is probable that example.com has given user Bob control over the DID in question, and proofs of control refer to Bob rather than all of example.com.

2.6.7 Cross-Origin Resource Sharing (CORS) Policy Considerations

To support scenarios where DID resolution is performed by client applications running in a web browser, the file served for the DID document should be accessible by any origin. To enable this, the DID document HTTP response can be set to include the following header: 

Access-Control-Allow-Origin: *

A. Reference implementations

This section is non-normative.

The code at uport-project/https-did-resolver is intended to present a reference implementation of this DID method. Any other implementations should ensure that they pass the test suite described in /src/__tests__ before claiming compatibility.

The code at transmute-industries/restricted-resolver implements this specification.

The code at reinkrul/java-did-resolvers implements this specification as a Java library.

B. References

B.1 Normative references

[DID-CORE]
Decentralized Identifiers (DIDs) v1.0. Manu Sporny; Amy Guy; Markus Sabadello; Drummond Reed. W3C. 19 July 2022. W3C Recommendation. URL: https://www.w3.org/TR/did-core/
[RFC1035]
Domain names - implementation and specification. P. Mockapetris. IETF. November 1987. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc1035
[RFC1123]
Requirements for Internet Hosts - Application and Support. R. Braden, Ed. IETF. October 1989. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc1123
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC2181]
Clarifications to the DNS Specification. R. Elz; R. Bush. IETF. July 1997. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc2181
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[RFC8484]
DNS Queries over HTTPS (DoH). P. Hoffman; P. McManus. IETF. October 2018. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc8484

B.2 Informative references

[DID-PRIMER]
DID Primer. Drummond Reed; Manu Sporny. Rebooting the Web of Trust 2017. URL: https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-fall2017/blob/master/topics-and-advance-readings/did-primer.md
[OWASP-TRANSPORT]
Transport Layer Protection Cheatsheet. URL: https://www.owasp.org/index.php/Transport_Layer_Protection_Cheat_Sheet